home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / QD3DView.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-13  |  14.5 KB  |  456 lines  |  [TEXT/MPS ]
  1. /******************************************************************************
  2.  **                                                                             **
  3.  **     Module:        QD3DView.h                                                 **
  4.  **                                                                             **
  5.  **                                                                             **
  6.  **     Purpose:     View types and routines                                     **
  7.  **                                                                             **
  8.  **                                                                             **
  9.  **                                                                             **
  10.  **     Copyright (C) 1992-1997 Apple Computer, Inc.  All rights reserved.     **
  11.  **                                                                             **
  12.  **                                                                             **
  13.  *****************************************************************************/
  14. #ifndef QD3DView_h
  15. #define QD3DView_h
  16.  
  17. #include "QD3D.h"
  18. #include "QD3DStyle.h"
  19. #include "QD3DSet.h"
  20.  
  21. #if defined(PRAGMA_ONCE) && PRAGMA_ONCE
  22.     #pragma once
  23. #endif  /*  PRAGMA_ONCE  */
  24.  
  25. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  26.  
  27. #if defined(__xlc__) || defined(__XLC121__)
  28.     #pragma options enum=int
  29.     #pragma options align=power
  30. #elif defined(__MWERKS__)
  31.     #pragma enumsalwaysint on
  32.     #pragma options align=native
  33. #elif defined(__MRC__) || defined(__SC__)
  34.     #if __option(pack_enums)
  35.         #define PRAGMA_ENUM_RESET_QD3DVIEW 1
  36.     #endif
  37.     #pragma options(!pack_enums)
  38.     #pragma options align=power
  39. #endif
  40.  
  41. #endif  /* OS_MACINTOSH */
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif    /* __cplusplus */
  46.  
  47.  
  48. /******************************************************************************
  49.  **                                                                             **
  50.  **                        View Type Definitions                                 **
  51.  **                                                                             **
  52.  *****************************************************************************/
  53.  
  54. typedef enum TQ3ViewStatus {
  55.     kQ3ViewStatusDone,
  56.     kQ3ViewStatusRetraverse,
  57.     kQ3ViewStatusError,
  58.     kQ3ViewStatusCancelled
  59. } TQ3ViewStatus;
  60.  
  61.  
  62. /******************************************************************************
  63.  **                                                                             **
  64.  **                        Default Attribute Set                                 **
  65.  **                                                                             **
  66.  *****************************************************************************/
  67.  
  68. #define kQ3ViewDefaultAmbientCoefficient    1.0
  69. #define kQ3ViewDefaultDiffuseColor            0.5, 0.5, 0.5
  70. #define kQ3ViewDefaultSpecularColor            0.5, 0.5, 0.5
  71. #define kQ3ViewDefaultSpecularControl        4.0
  72. #define kQ3ViewDefaultTransparency            1.0, 1.0, 1.0
  73. #define kQ3ViewDefaultHighlightState        kQ3Off
  74. #define kQ3ViewDefaultHighlightColor        1.0, 0.0, 0.0
  75.  
  76. #define kQ3ViewDefaultSubdivisionMethod        kQ3SubdivisionMethodScreenSpace
  77. #define kQ3ViewDefaultSubdivisionC1            20.0
  78. #define kQ3ViewDefaultSubdivisionC2            20.0
  79.  
  80.  
  81. /******************************************************************************
  82.  **                                                                             **
  83.  **                            View Routines                                     **
  84.  **                                                                             **
  85.  *****************************************************************************/
  86.  
  87. QD3D_EXPORT TQ3ViewObject QD3D_CALL Q3View_New(
  88.     void);
  89.  
  90. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_Cancel(
  91.     TQ3ViewObject        view);
  92.  
  93.  
  94. /******************************************************************************
  95.  **                                                                             **
  96.  **                        View Rendering routines                                 **
  97.  **                                                                             **
  98.  *****************************************************************************/
  99.  
  100. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetRendererByType(
  101.     TQ3ViewObject         view,
  102.     TQ3ObjectType         type);
  103.     
  104. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetRenderer(
  105.     TQ3ViewObject         view,
  106.     TQ3RendererObject    renderer);
  107.  
  108. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetRenderer(
  109.     TQ3ViewObject        view,
  110.     TQ3RendererObject    *renderer);
  111.     
  112. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_StartRendering(
  113.     TQ3ViewObject         view);
  114.     
  115. QD3D_EXPORT TQ3ViewStatus QD3D_CALL Q3View_EndRendering(
  116.     TQ3ViewObject         view);
  117.     
  118. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_Flush(
  119.     TQ3ViewObject        view);
  120.     
  121. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_Sync(
  122.     TQ3ViewObject        view);
  123.  
  124.  
  125. /******************************************************************************
  126.  **                                                                             **
  127.  **                        View/Bounds/Pick routines                             **
  128.  **                                                                             **
  129.  *****************************************************************************/
  130.  
  131. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_StartBoundingBox(
  132.     TQ3ViewObject        view,
  133.     TQ3ComputeBounds    computeBounds);
  134.  
  135. QD3D_EXPORT TQ3ViewStatus QD3D_CALL Q3View_EndBoundingBox(
  136.     TQ3ViewObject        view,
  137.     TQ3BoundingBox        *result);
  138.  
  139. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_StartBoundingSphere(
  140.     TQ3ViewObject        view,
  141.     TQ3ComputeBounds    computeBounds);
  142.  
  143. QD3D_EXPORT TQ3ViewStatus QD3D_CALL Q3View_EndBoundingSphere(
  144.     TQ3ViewObject        view,
  145.     TQ3BoundingSphere    *result);
  146.  
  147. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_StartPicking(
  148.     TQ3ViewObject        view,
  149.     TQ3PickObject        pick);
  150.  
  151. QD3D_EXPORT TQ3ViewStatus QD3D_CALL Q3View_EndPicking(
  152.     TQ3ViewObject        view);
  153.  
  154.  
  155. /******************************************************************************
  156.  **                                                                             **
  157.  **                            View/Camera routines                             **
  158.  **                                                                             **
  159.  *****************************************************************************/
  160.  
  161. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetCamera(
  162.     TQ3ViewObject        view,
  163.     TQ3CameraObject        *camera);
  164.  
  165. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetCamera(
  166.     TQ3ViewObject        view,
  167.     TQ3CameraObject        camera);
  168.  
  169.  
  170.  
  171. /******************************************************************************
  172.  **                                                                             **
  173.  **                            View/Lights routines                             **
  174.  **                                                                             **
  175.  *****************************************************************************/
  176.  
  177. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetLightGroup(
  178.     TQ3ViewObject        view,
  179.     TQ3GroupObject        lightGroup);
  180.  
  181. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetLightGroup(
  182.     TQ3ViewObject        view,
  183.     TQ3GroupObject        *lightGroup);
  184.  
  185.  
  186. /******************************************************************************
  187.  **                                                                             **
  188.  **                                Idle Method                                     **
  189.  **                                                                             **
  190.  *****************************************************************************/
  191. /*
  192.  *    The idle methods allow the application to register callback routines 
  193.  *    which will be called by the view during especially long operations.
  194.  *
  195.  *    The idle methods may also be used to interrupt long renderings or
  196.  *    traversals.  Inside    the idler callback the application can check for
  197.  *    Command-Period, Control-C or clicking a "Cancel" button or whatever else
  198.  *    may be used to let the user interrupt rendering.    
  199.  *
  200.  *    It is NOT LEGAL to call QD3D routines inside an idler callback.
  201.  *
  202.  *    Return kQ3Failure to cancel rendering, kQ3Success to continue. Don't
  203.  *    bother posting an error.
  204.  *
  205.  *    Q3View_SetIdleMethod registers a callback that can be called
  206.  *    by the system during rendering.  Unfortunately there is no way yet
  207.  *    to set timer intervals when you want to be called.  Basically, it is
  208.  *    up to the application's idler callback to check clocks to see if you
  209.  *    were called back only a millisecond ago or an hour ago!
  210.  *
  211.  *    Q3View_SetIdleProgressMethod registers a callback that also gives
  212.  *    progress information. This information is supplied by the renderer, and
  213.  *    may or may not be based on real time.
  214.  *
  215.  *    If a renderer doesn't support the progress method, your method will be
  216.  *    called with current == 0 and completed == 0.
  217.  *    
  218.  *    Otherwise, you are GUARANTEED to get called at least 2 or more times:
  219.  *    
  220.  *    ONCE            idleMethod(view, 0, n)        -> Initialize, Show Dialog
  221.  *    zero or more    idleMethod(view, 1..n-1, n) -> Update progress
  222.  *    ONCE            idleMethod(view, n, n)        -> Exit, Hide Dialog
  223.  *    
  224.  *    "current" is guaranteed to be less than or equal to "completed"
  225.  *    "completed" may change values, but current/complete always indicates
  226.  *    the degree of completion.
  227.  *
  228.  *    The calling conventions aid in managing any data associated with a 
  229.  *    progress user interface indicator.
  230. */
  231.  
  232. typedef TQ3Status (QD3D_CALLBACK *TQ3ViewIdleMethod)(
  233.     TQ3ViewObject        view,
  234.     const void            *idlerData);
  235.  
  236. typedef TQ3Status (QD3D_CALLBACK *TQ3ViewIdleProgressMethod)(
  237.     TQ3ViewObject        view,
  238.     const void            *idlerData,
  239.     unsigned long        current,
  240.     unsigned long        completed);
  241.  
  242. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetIdleMethod(
  243.     TQ3ViewObject        view,
  244.     TQ3ViewIdleMethod    idleMethod,
  245.     const void             *idleData);
  246.  
  247. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetIdleProgressMethod(
  248.     TQ3ViewObject                view,
  249.     TQ3ViewIdleProgressMethod    idleMethod,
  250.     const void                     *idleData);
  251.  
  252. /******************************************************************************
  253.  **                                                                             **
  254.  **                                EndFrame Method                                 **
  255.  **                                                                             **
  256.  *****************************************************************************/
  257.  
  258. /*
  259.  *    The end frame method is an alternate way of determining when an
  260.  *    asynchronous renderer has completed rendering a frame. It differs from
  261.  *    Q3View_Sync in that notification of the frame completion is the opposite
  262.  *    direction. 
  263.  *    
  264.  *    With Q3View_Sync the application asks a renderer to finish rendering
  265.  *    a frame, and blocks until the frame is complete.
  266.  *    
  267.  *    With the EndFrame method, the renderer tells the application that is has
  268.  *    completed a frame.
  269.  *
  270.  *    If "Q3View_Sync" is called BEFORE this method has been called, this
  271.  *    method will NOT be called ever.
  272.  *    
  273.  *    If "Q3View_Sync" is called AFTER this method has been called, the
  274.  *    call will return immediately (as the frame has already been completed).
  275.  */
  276.  
  277. typedef void (QD3D_CALLBACK *TQ3ViewEndFrameMethod)(
  278.     TQ3ViewObject            view,
  279.     void                    *endFrameData);
  280.  
  281. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetEndFrameMethod(
  282.     TQ3ViewObject            view,
  283.     TQ3ViewEndFrameMethod    endFrame,
  284.     void                     *endFrameData);
  285.  
  286. /******************************************************************************
  287.  **                                                                             **
  288.  **                            Push/Pop routines                                 **
  289.  **                                                                             **
  290.  *****************************************************************************/
  291.  
  292. QD3D_EXPORT TQ3Status QD3D_CALL Q3Push_Submit(
  293.     TQ3ViewObject     view);
  294.  
  295. QD3D_EXPORT TQ3Status QD3D_CALL Q3Pop_Submit(
  296.     TQ3ViewObject     view);
  297.  
  298.  
  299. /******************************************************************************
  300.  **                                                                             **
  301.  **        Check if bounding box is visible in the viewing frustum.  Transforms **
  302.  **        the bbox by the current local_to_world transformation matrix and     **
  303.  **        does a clip test to see if it lies in the viewing frustum.             **
  304.  **        This can be used by applications to cull out large chunks of scenes     **
  305.  **        that are not going to be visible.                                     **
  306.  **                                                                             **
  307.  **        The default implementation is to always return kQ3True.  Renderers     **
  308.  **        may override this routine however to do the checking.                 **
  309.  **                                                                             **
  310.  *****************************************************************************/
  311.  
  312. QD3D_EXPORT TQ3Boolean QD3D_CALL Q3View_IsBoundingBoxVisible(
  313.     TQ3ViewObject            view,
  314.     const TQ3BoundingBox    *bbox);
  315.  
  316.  
  317. /******************************************************************************
  318.  **                                                                             **
  319.  **                            DrawContext routines                             **
  320.  **                                                                             **
  321.  *****************************************************************************/
  322.  
  323. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetDrawContext(
  324.     TQ3ViewObject             view,
  325.     TQ3DrawContextObject    drawContext);
  326.  
  327. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetDrawContext(
  328.     TQ3ViewObject             view,
  329.     TQ3DrawContextObject    *drawContext);
  330.  
  331.  
  332. /******************************************************************************
  333.  **                                                                             **
  334.  **                            Graphics State routines                             **
  335.  **                                                                             **
  336.  ** The graphics state routines can only be called while rendering (ie. in     **
  337.  ** between calls to start and end rendering calls).  If they are called     **
  338.  ** outside of a rendering loop, they will return with error.                 **
  339.  **                                                                             **
  340.  *****************************************************************************/
  341.   
  342. /******************************************************************************
  343.  **                                                                             **
  344.  **                            Transform routines                                 **
  345.  **                                                                             **
  346.  *****************************************************************************/
  347.  
  348. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetLocalToWorldMatrixState(
  349.     TQ3ViewObject        view,
  350.     TQ3Matrix4x4        *matrix);
  351.         
  352. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetWorldToFrustumMatrixState(
  353.     TQ3ViewObject        view,
  354.     TQ3Matrix4x4        *matrix);
  355.         
  356. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetFrustumToWindowMatrixState(
  357.     TQ3ViewObject        view,
  358.     TQ3Matrix4x4        *matrix);
  359.     
  360.  
  361. /******************************************************************************
  362.  **                                                                             **
  363.  **                            Style state routines                             **
  364.  **                                                                             **
  365.  *****************************************************************************/
  366.  
  367. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetBackfacingStyleState(
  368.     TQ3ViewObject            view,
  369.     TQ3BackfacingStyle        *backfacingStyle);
  370.  
  371. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetInterpolationStyleState(
  372.     TQ3ViewObject            view,
  373.     TQ3InterpolationStyle    *interpolationType);
  374.  
  375. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetFillStyleState(
  376.     TQ3ViewObject            view,
  377.     TQ3FillStyle            *fillStyle);
  378.  
  379. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetHighlightStyleState(
  380.     TQ3ViewObject            view,
  381.     TQ3AttributeSet            *highlightStyle);
  382.  
  383. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetSubdivisionStyleState(
  384.     TQ3ViewObject            view,
  385.     TQ3SubdivisionStyleData    *subdivisionStyle);
  386.  
  387. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetOrientationStyleState(
  388.     TQ3ViewObject            view,
  389.     TQ3OrientationStyle        *fontFacingDirectionStyle);
  390.  
  391. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetReceiveShadowsStyleState(
  392.     TQ3ViewObject            view,
  393.     TQ3Boolean                *receives);
  394.  
  395. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetPickIDStyleState(
  396.     TQ3ViewObject            view,
  397.     unsigned long            *pickIDStyle);
  398.     
  399. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetPickPartsStyleState(
  400.     TQ3ViewObject            view,
  401.     TQ3PickParts            *pickPartsStyle);
  402.  
  403. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetAntiAliasStyleState(
  404.     TQ3ViewObject            view,
  405.     TQ3AntiAliasStyleData    *antiAliasData);
  406.     
  407.  
  408. /******************************************************************************
  409.  **                                                                             **
  410.  **                        Attribute state routines                             **
  411.  **                                                                             **
  412.  *****************************************************************************/
  413.  
  414. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetDefaultAttributeSet(
  415.     TQ3ViewObject        view,
  416.     TQ3AttributeSet        *attributeSet);
  417.  
  418. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_SetDefaultAttributeSet(
  419.     TQ3ViewObject        view,
  420.     TQ3AttributeSet        attributeSet);
  421.  
  422.  
  423. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetAttributeSetState(
  424.     TQ3ViewObject         view,
  425.     TQ3AttributeSet        *attributeSet);
  426.  
  427. QD3D_EXPORT TQ3Status QD3D_CALL Q3View_GetAttributeState(
  428.     TQ3ViewObject         view,
  429.     TQ3AttributeType    attributeType,
  430.     void                *data);
  431.  
  432.  
  433. #ifdef __cplusplus
  434. }
  435. #endif    /* __cplusplus */
  436.  
  437. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  438.  
  439. #if defined(__xlc__) || defined(__XLC121__)
  440.     #pragma options enum=reset
  441.     #pragma options align=reset
  442. #elif defined(__MWERKS__)
  443.     #pragma enumsalwaysint reset
  444.     #pragma options align=reset
  445. #elif defined(__MRC__) || defined(__SC__)
  446.     #if PRAGMA_ENUM_RESET_QD3DVIEW
  447.         #pragma options(pack_enums)
  448.         #undef PRAGMA_ENUM_RESET_QD3DVIEW
  449.     #endif
  450.     #pragma options align=reset
  451. #endif
  452.  
  453. #endif  /* OS_MACINTOSH */
  454.  
  455. #endif  /*  QD3DView_h  */
  456.